libURLMultipartFormData

Type

function

Summary

libURLMultipartFormData formats data in the way described in RFC 1867.

Syntax

libURLMultipartFormData(<formData>, <key1>, <value1> [, <key2>, <value2> ...])

libURLMultipartFormData(<formData>, <array>)

libURLMultipartFormData(<formData>)

Description

The function can be called in a number of ways depending on the parameters passed. In all cases, the first parameter must be a variable which will be filled with the form data. The function will return empty if successful, or an error message if it fails (for example, if it couldn't open a file).

note

When you need to supply a file as the value of a parameter, you must pass the file name preceeded by the text "<file>".

note

In all cases, the first line of the data returned in the formData variable is the Content-Type header that must be included in the httpHeaders of the url request. Lines 2 to the end of the data is the data that must be posted to the url.

The standard way to call the function is with pairs of name/value parameters.

You can also pass in an array instead of pairs of parameters. This could be useful if there are many parts to a form. The array must be numerically indexed, and each element should contain the part name and part value, separated by a comma. So (modifying the above example):

    local tForm, tError, tUrl, tName, tMessage, tArray, tFile
    put empty into tForm
    put \"dave\" into tName
    put \"hello\" into tMessage
    put \"<file>\" & \"C:/myfile.txt\" into tFile
    put \"name,\" & tName into tArray[1]
    put \"message,\" & tMessage into tArray[2]
    put \"file,\" & tFile into tArray[3]
    put libURLMultipartFormData(tForm, tArray) into tError
    if tError is not empty then
      answer tError 
    else
      set the httpHeaders to line 1 of tForm
      post line 2 to -1 of tForm to url tUrl
      set the httpHeaders to empty
    end if

You can also call the function with no arguments except formData. This will return an "empty" form. Basically, line 1 is the header, and line 2 is the final boundary mark of the form. It is of no use by itself, but it can be used with libURLMultipartFormAddPart.

Important

The libURLMultipartFormData function is part of the Internet library. To ensure that the function works in a standalone application, you must include this custom library when you create your standalone. In the Inclusions pane of the Standalone Application Settings window, make sure the "Internet" script library is selected.

See also RFC 1867.

Parameters

Name	Type	Description
formData		A variable, which will be filled with the form data.
key1
value1
key2
value2
array

Examples

local tForm, tError, tUrl, tName, tMessage, tFile
put empty into tForm
put "http://www.someserver.com/cgi-bin/form.cgi" into tUrl
put "dave" into tName 
put "hello" into tMessage
put "<file>" & "C:/myfile.txt" into tFile
put libURLMultipartFormData \
 (tForm, "name", tName, "message", tMessage, "file", tFile) \
 into tError
if tError is not empty then
 answer tError
else
 set the httpHeaders to line 1 of tForm
 post line 2 to -1 of tForm to url tUrl
 ## check the result, etc., here
 set the httpHeaders to empty
end if

Related

function: libURLFormData, libURLMultipartFormAddPart

glossary: argument, function, LiveCode custom library, parameter, standalone application, Standalone Application Settings

keyword: $_POST, $_POST_BINARY, $_POST_RAW

library: Internet library, library

command: libURLSetExpect100, post

Compatibility and Support

Introduced

LiveCode 2.5

OS

mac

windows

linux

web

Platforms

desktop

server